Txt2Site creates websites. Pages are created using a HTML template. The layout of pages can be beautified by stylesheets.
The content part of a page is defined by a text file. These text files are located in the content directory of the application. The directory structure of the content directory reflects the page structure of the website.

If you provide Txt2Site with:

• a template directory with a HTML template file
• an include directory with stylesheet(s), images, javascript, ...
• a content directory with content for the website organized as text files in subdirectories

Then Txt2Site provides you with a website:

• it locates the website in a target directory on your computer
• it looks according to the HTML template and stylesheet(s) and is filled with your content
• it has generated a navigation menu
• it uses relative references so you can move and view your website at the location you want

Application data

All application data is located in one parent directory, the root directory of the application. The configuration file is always located in the root directory. The configuration file tells Txt2Site the location of files such as content files and templates, and where to put the new website. If not specified in the config file, Txt2Site uses a default directory structure.

Default directory structure The default directory structure is drawn next to with a root directory called my_demo. The default configuration is declared as: - content_dir=content - include_dir=include - template_dir=templates - target_dir=site/target - style_dir= The directories are declared relative to the application root. See the examples section for some alternative directory structures.

Main scripts

Txt2Site provides two main scripts:

1. A script to establish a default application environment
2. A script to create or update a website

The first script creates an environment in the working directory with a default directory structure. It also creates a content file with some content to test. The command to execute this script is:

  $ txt2site -n my_demo 

Here my_demo is the name of the root directory. As you expect the root directory is created in the current working directory. It creates a new demo application with a config file called my_demo.conf.
The base color of the demo website is by default green. If you insert one of the colors red, green, yellow, grey or blue in the name of the application, then this color is the base color of the website.

The second script creates/updates the website based on the content files. After you update the content files you can execute it again. The command to execute this script is:

  $ txt2site  -g  my_demo/my_demo.conf 

The command with option -g (generate) has the config file as argument. The path of the config file is relative to the working directory. If the config file does not exist, the command finishes with an error message.

Processing steps for creating a website

The next drawing shows you broadly how Txt2Site processes data when creating a website.

In terms of the default application structure the following steps are executed to generate a website:

1. read the config file (for the directory structure and user defined site variables)
2. remove all files and directories in the directory site/target
3. for each content file in the content directory:
   1. read the content file
   2. read user defined page variables
   3. init system variables
      • an important variable is path_to_root which uses relative paths
   4. read the template file and evaluate variables and functions defined by the user
      1. evaluate variables appearing as ${variable_name}
      2. evaluate functions appearing as $(function_name)
         • insert and evaluate content sections and translate it to XHTML according to the page_format
         • insert navigation menus and/or breadcrumbs
   5. create a new page with the updated template file
   6. put the new page in the right subdirectory of the directory site/target
4. copy the include directory to the site/target directory
5. evaluate stylesheets if the style_dir variable is not empty and valid

Using variables and functions

Variables are defined and get a value (string) in three ways:

1. by the user in the configuration file, used as globals on the whole site
2. by the user in the header section of a content file, used as locals on a page
3. by the system, used as globals on the whole site (see chapter System Variables)

A variable can be called everywhere in a content section, template file or stylesheet by typing:

                     ${variable-name}

Using a variable in this manner, Txt2Site will substitute its value when generating a new site.

Functions are defined by the system. While variables has a string as value, functions can have multiple lines as output. These lines can be user defined or system defined. For example a user defined output is generated by the function html_content_div which outputs a content section to be included in a page. A system defined output is generated by the function html_mainmenu_div which outputs a navigation menu.
The result of a function can be inserted everywhere in a content section or template file by typing:

                     $(function-name)

In case of two arguments, the syntax is: $(function-name arg1 arg2).

Once defined, variables and functions can be used in content sections, template files and stylesheets.
The process of replacing all variables and functions with its value is called evaluation.
For each generated page there are two evaluation steps:

1. The first step is evaluating variables and functions in the template file for the page.
   
2. The second step is evaluating variables and functions in a content section after adding this content to the page. This happens if you add content with the functions html_content_div or include_file.

The evaluation of the template file is always performed, the second evaluation can be prevented if you want by giving the second argument of these functions the value "noeval".
Benefits of not evaluating variables and functions (if any) is, you can freely use the dollar symbol in your text and it gives you a slightly better performance. If evaluation must be performed, you had to hide the dollar symbol where you do not want it to evaluate by Txt2Site.

Once the website is generated, a last evaluation step is performed, where variables in the stylesheets are replaced by their value. See stylesheet variables in the section File Types.

For more information about a particular variable or function see the chapters System Functions and System Variables.

See the Tutorial chapter for examples how to maintain your website.